Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Introduction
OpenDoc provides users the ability to customize their OpenDoc runtime by installing OpenDoc Shell Plug-Ins, similar to the way users can customize their MacOS™ System Folder by installing Extensions (INITs). An OpenDoc Shell Plug-In is simply a CFM shared library located in the OpenDoc Shell Plug-Ins folder and that exports a symbol called ODShellPlugInInstall. This document provides sample code for implementing a Shell Plug-In.
Elements
1. Create a source file with an entry point called ODShellPlugInInstall. If using C++, be sure to type it "extern "C"" so that the right calling conventions will be used.
2. Set up your build system to produce a CFM shared library from the source file, and to have the library export the symbol "ODShellPlugInInstall". Compile and link the library.
Installation
Once you have successfuly built the shared library, drop it into your OpenDoc Shell Plug-Ins folder. Remember that the name of this folder, and of its containing folders, may differ on non-Roman Mac systems, but on Roman systems it's ":System Folder:Editors:OpenDoc:OpenDoc Shell Plug-Ins:".
Sample Code Overview
• ODShellPlugIn C or C++ code:
#include <types.h>
#include <ODTypesB.xh>
#include "ShPlugIn.h"
#include <TextUtils.h>
// You probably want to #include the .xh files that define these classes,
// so that, for instance, you can get the session from the draft, but all
// we care about is that our simple example compile....
// Now tell the Shell to close the connection to our library as soon
// as we return.
// This isn't what most plugins will want to do, but it's the right
// thing to do if you're just displaying a debugstr :-). If you wanted
// to leave the library open, say because you'd registered an object
// in an object namespace, you'd clear the kODShellPluginCloseConnection
// bit if paranoid, or otherwise just leave *action alone.
*action |= kODShellPluginCloseConnection;
// Return noErr if you want the Shell to continue starting up. Any other
// error causes the Shell to abort with a dialog telling the user what
// plugin it was attempting to load when the error occurred and suggesting
// that he remove it from the plugins folder before attempting to open
// the document again.
// Note that the Shell ignores errors returned via the Environment*
// parameter. Pass ev to OpenDoc routines that you call from here if
// they require it, but if any of them returns an error that way you'll
// have to deal with it yourself (if it needs dealing with at all.) If the
// Shell gets noErr back from your plugin it assumes all is well and
// continues.
return noErr;
}
• Building your library:
Building a CFM shared library generally requires both source files and a .exp file telling the linker what symbols/entry points to export. My example build commands below assume a source file called "SmpPlgin.cpp" and a .exp file called "SmpPlgin.exp" that is a TEXT file consisting of one line: "ODShellPlugInInstall". Given those two files in a folder, and MPW set with that folder as its current directory and with the MPW shell variable OpenDocInterfaces holding the path to your OpenDoc interface files (.xh files), the following commands will build a Shell Plug-in library named SamplePlugin.
SCpp -i "{OpenDocInterfaces}" ∂
-model cfmflat SmpPlgin.cpp
ilink -xm s -model cfmflat -@export SmpPlgin.exp ∂
